---
title: 가져오기 참조
description: Astro 프로젝트에 다양한 파일 타입을 가져오는 방법 알아보기
i18nReady: true
---
import RecipeLinks from '~/components/RecipeLinks.astro';
import ReadMore from '~/components/ReadMore.astro';

Astro는 구성이 필요하지 않은 대부분의 정적 자산을 지원합니다. 프로젝트 JavaScript (Astro 프런트매터 포함) 어디에서나 `import` 문을 사용할 수 있으며, Astro는 최종 빌드에 해당 정적 자산의 빌드되고 최적화된 복사본을 포함합니다. `@import`는 CSS 및 `<style>` 태그에서도 지원됩니다.

## 지원되는 파일 형식

Astro에서는 기본적으로 다음 파일 형식을 지원합니다.

- Astro 컴포넌트 (`.astro`)
- Markdown (`.md`, `.markdown` 등)
- JavaScript (`.js`, `.mjs`)
- TypeScript (`.ts`)
- NPM 패키지
- JSON (`.json`)
- CSS (`.css`)
- CSS 모듈 (`.module.css`)
- 이미지 및 자산 (`.svg`, `.jpg`, `.png` 등)

또한 Astro를 확장하여 React, Svelte, Vue 컴포넌트와 같은 다양한 [UI 프레임워크](/ko/guides/framework-components/)에 대한 지원을 추가할 수 있습니다. `.mdx` 또는 `.mdoc` 파일을 프로젝트에서 사용하기 위해 [Astro MDX 통합](/ko/guides/integrations-guide/mdx/) 또는 [Astro Markdoc 통합](/ko/guides/integrations-guide/markdoc/)을 설치할 수도 있습니다.

### `public/` 디렉터리 내 파일

프로젝트의 [`public/` 디렉터리](/ko/basics/project-structure/#public)에 정적 자산을 배치할 수 있으며 Astro는 이를 그대로 최종 빌드에 직접 복사합니다. `public/` 파일은 Astro에서 빌드되거나 번들로 제공되지 않습니다. 즉, 모든 유형의 파일이 지원된다는 의미입니다. 

HTML 템플릿에서 직접 URL 경로로 `public/` 파일을 참조할 수 있습니다.

```astro
// /public/reports/annual/2024.pdf 링크
Download the <a href="/reports/annual/2024.pdf">2024 annual statement as a PDF</a>.

// /public/assets/cats/ginger.jpg 표시
<img src="/assets/cats/ginger.jpg" alt="An orange cat sleeping on a bed.">
```

## Import 구문

Astro는 브라우저에서 지원되는 것과 동일한 [`import`](https://developer.mozilla.org/ko/docs/Web/JavaScript/Reference/Statements/import) 및 [`export`](https://developer.mozilla.org/ko/docs/Web/JavaScript/Reference/Statements/export) 구문인 ESM을 사용합니다.

### JavaScript

```js
import { getUser } from './user.js';
```

JavaScript는 일반적인 ESM `import` & `export` 구문을 사용하여 가져올 수 있습니다.

:::note[JSX 파일 가져오기]

JSX/TSX 파일을 렌더링하려면 적절한 [UI 프레임워크](/ko/guides/framework-components/) ([React](/ko/guides/integrations-guide/react/), [Preact](/ko/guides/integrations-guide/preact/), [Solid](/ko/guides/integrations-guide/solid-js/))가 있어야 합니다.
Astro는 `.js`/`.ts` 파일에서 JSX를 지원하지 않으므로 적절한 경우 `.jsx`/`.tsx` 확장자를 사용하세요.

:::

### TypeScript

```js
import { getUser } from './user';
import type { UserType } from './user';
```

Astro에는 [TypeScript](https://www.typescriptlang.org/ko/)에 대한 지원이 내장되어 있습니다. Astro 프로젝트에서 직접 `.ts` 및 `.tsx` 파일을 가져올 수 있으며. [Astro 컴포넌트 스크립트](/ko/basics/astro-components/#컴포넌트-스크립트) 및 [스크립트 태그](/ko/guides/client-side-scripts/)에 TypeScript 코드를 직접 작성할 수도 있습니다.

**Astro는 자체적으로 어떠한 타입 검사도 수행하지 않습니다.** 타입 검사는 Astro 외부에서 IDE나 별도의 스크립트를 통해 처리해야 합니다. Astro 파일의 타입 검사를 위해 [`astro check` 명령](/ko/reference/cli-reference/#astro-check)이 제공됩니다.

:::note[TypeScript 및 파일 확장자]
[TypeScript의 모듈 확인 규칙](https://www.typescriptlang.org/docs/handbook/module-resolution.html)에 따라 TypeScript 파일을 가져올 때 `.ts` 및 `.tsx` 파일 확장자를 사용하면 안 됩니다. 대신 `.js`/`.jsx` 파일 확장자를 사용하거나 파일 확장자를 완전히 생략하세요.

```ts
import { getUser } from './user.js'; // user.ts
import MyComponent from './MyComponent'; // MyComponent.tsx
```
:::

<ReadMore>[Astro의 TypeScript 지원](/ko/guides/typescript/)에 대해 자세히 알아보세요.</ReadMore>

### NPM 패키지

NPM 패키지를 설치한 경우 Astro로 가져올 수 있습니다.

```astro
---
import { Icon } from 'astro-icon';
---
```

패키지가 레거시 형식을 사용하여 게시된 경우 Astro는 `import` 문이 작동하도록 패키지를 ESM으로 변환하려고 시도합니다. 어떤 경우에는 [`vite` 구성](/ko/reference/configuration-reference/#vite)을 조정해야 작동할 수도 있습니다.

:::caution
일부 패키지는 브라우저 환경에 의존합니다. Astro 컴포넌트는 서버에서 실행되므로 프런트매터에서 이러한 패키지를 가져오면 [오류가 발생할 수 있습니다](/ko/guides/troubleshooting/#document-or-window-is-not-defined).
:::

### JSON

```js
// 기본 내보내기를 통해 JSON 객체 불러오기
import json from './data.json';
```

Astro는 JSON 파일을 애플리케이션으로 직접 가져오는 것을 지원합니다. 가져온 파일은 기본 가져오기에서 전체 JSON 객체를 반환합니다.

### CSS

```js
// 페이지에 'style.css' 불러오기 및 삽입
import './style.css';
```

Astro는 CSS 파일을 애플리케이션으로 직접 가져오는 것을 지원합니다. 가져온 스타일은 내보내기를 노출하지 않지만 스타일을 가져오면 해당 스타일이 페이지에 자동으로 추가됩니다. 이는 기본적으로 모든 CSS 파일에 대해 작동하며 플러그인을 통해 Sass & Less와 같은 CSS로 컴파일 언어를 지원할 수 있습니다.

<ReadMore>[스타일링 가이드](/ko/guides/styling/#고급)에서 CSS 파일에 대한 직접 URL 참조 또는 문자열로 CSS 가져오기 등 고급 CSS 가져오기 사용 사례에 대해 자세히 알아보세요.</ReadMore>

### CSS 모듈

```jsx
// 1. './style.module.css' 클래스 이름을 고유한 범위 값으로 변환합니다.
// 2. 원래 클래스 이름을 최종 범위 값에 매핑하는 객체를 반환합니다.
import styles from './style.module.css';

// 이 예시에서는 JSX를 사용하지만 모든 프레임워크에서 CSS 모듈을 사용할 수 있습니다.
return <div className={styles.error}>에러 메시지</div>;
```

Astro는 `[name].module.css` 명명 규칙을 사용하여 CSS 모듈을 지원합니다. 다른 CSS 파일과 마찬가지로 파일을 가져오면 해당 CSS가 페이지에 자동으로 적용됩니다. 그러나 CSS 모듈은 원래 클래스 이름을 고유 식별자에 매핑하는 특별한 기본 `styles` 객체를 내보냅니다.

CSS 모듈은 스타일시트에 대해 고유하게 생성된 클래스 이름을 사용하여 프런트엔드에서 컴포넌트 범위 지정 및 격리를 적용하는 데 도움이 됩니다.

### 기타 자산

```jsx
// `src` 및 기타 속성을 가진 객체를 반환합니다.
import imgReference from './image.png';
import svgReference from './image.svg';

// HTML이나 UI 프레임워크 컴포넌트는 이미지를 렌더링하기 위해 이 방법을 사용합니다.
<img src={imgReference.src} alt="이미지 설명" />;

// Astro의 `<Image />` 및 `<Picture />` 컴포넌트는 기본적으로 `src`에 접근합니다.
<Image src={imgReference} alt="이미지 설명">
```

위에서 명시적으로 언급되지 않은 모든 기타 자산은 ESM `import`를 통해 가져올 수 있으며, 객체 대신 최종 빌드된 자산에 대한 URL 참조 (예: `/_astro/my-video.C7vXpQtF.mp4`)를 반환합니다.

이는 `src` 속성이 해당 이미지를 가리키는 비디오 요소를 생성하는 경우처럼 URL을 통해 JavaScript가 아닌 자산을 참조하는 데 유용할 수 있습니다.

[프로젝트 구조 페이지](/ko/basics/project-structure/#public)에 설명된 대로 `public/` 폴더에 이미지 및 기타 자산을 배치하는 것도 유용할 수 있습니다.

<ReadMore>Vite 가져오기 매개변수 (예: `?url`, `?raw`) 추가에 대한 자세한 내용은 [Vite의 정적 자산 처리 가이드](https://ko.vite.dev/guide/assets.html)를 참조하세요.</ReadMore>

:::note
접근성을 위해 `<img>` 태그에 **대체 텍스트**를 추가하는 것이 좋습니다! 이미지 요소에 `alt="유용한 설명"` 속성을 추가하는 것을 잊지 마세요. 이미지가 순전히 장식용인 경우 속성을 비워 둘 수 있습니다.
:::

## 별칭

**별칭**은 가져오기에 대한 바로가기를 만드는 방법입니다.

별칭은 디렉터리 또는 상대 경로에서 가져오는 경우가 많은 코드베이스의 개발 경험을 개선하는 데 도움이 됩니다.

```astro title="src/pages/about/company.astro" del="../../components" del="../../assets"
---
import Button from '../../components/controls/Button.astro';
import logoUrl from '../../assets/logo.png?url';
---
```

이 예에서 개발자는 `src/pages/about/company.astro`, `src/components/controls/Button.astro`, `src/assets/logo.png` 세 파일 간의 트리 관계를 이해해야 합니다. 그리고 `company.astro` 파일을 옮기려면 가져오는 경로도 함께 업데이트해야 합니다.

`tsconfig.json` 파일에서 별칭 가져오기를 추가할 수 있습니다.

```json title="tsconfig.json" ins={4-5}
{
  "compilerOptions": {
    "paths": {
      "@components/*": ["./src/components/*"],
      "@assets/*": ["./src/assets/*"]
    }
  }
}
```

이 구성이 변경되면 개발 서버가 자동으로 다시 시작됩니다. 이제 프로젝트의 어느 곳에서나 별칭을 사용하여 가져올 수 있습니다.

```astro title="src/pages/about/company.astro" ins="@components" ins="@assets"
---
import Button from '@components/controls/Button.astro';
import logoUrl from '@assets/logo.png?url';
---
```

## `import.meta.glob()`

[Vite의 `import.meta.glob()`](https://ko.vite.dev/guide/features.html#glob-import)는 glob 패턴을 사용하여 일치하는 파일 경로를 찾아 한 번에 여러 파일을 가져오는 방법입니다.

`import.meta.glob()`은 가져오고 싶은 로컬 파일과 일치하는 상대적인 [glob 패턴](#glob-패턴)을 매개변수로 받습니다. 일치하는 각 파일의 내보내기가 포함된 배열을 반환합니다. 일치하는 모든 모듈을 미리 로드하려면 두 번째 인수로 `{ eager: true }`를 전달하세요:

```astro title="src/components/my-component.astro" {3,4}
---
// `./src/pages/post/`에서 `.md`로 끝나는 모든 파일을 가져옵니다.
const matches = import.meta.glob('../pages/post/*.md', { eager: true }); 
const posts = Object.values(matches);
---

<!-- 처음 5개의 블로그 게시물에 대한 <article>을 렌더링합니다. -->
<div>
  {
    posts.slice(0, 4).map((post) => (
      <article>
        <h2>{post.frontmatter.title}</h2>
        <p>{post.frontmatter.description}</p>
        <a href={post.url}>계속 읽기</a>
      </article>
    ))
  }
</div>
```

`import.meta.glob`을 사용하여 가져온 Astro 컴포넌트는 [`AstroInstance`](#astro-파일) 타입입니다. `default` 속성을 사용하여 각 컴포넌트 인스턴스를 렌더링할 수 있습니다.

```astro title="src/pages/component-library.astro" {8}
---
// `./src/components/`에서 `.astro`로 끝나는 모든 파일을 가져옵니다.
const components = Object.values(import.meta.glob('../components/*.astro', { eager: true }));
---
<!-- 모든 컴포넌트 표시 -->{
  components.map((component) => (
    <div>
      <component.default size={24} />
    </div>
  ))
}
```

### 지원되는 값

Vite의 `import.meta.glob()` 함수는 정적 문자열 리터럴만 지원합니다. 동적 변수와 문자열 보간을 지원하지 않습니다.

일반적인 해결 방법은 필요한 모든 파일이 포함된 더 큰 파일 세트를 가져온 다음 필터링하는 것입니다:

```astro {6-7}
---
// src/components/featured.astro
const { postSlug } = Astro.props;
const pathToMyFeaturedPost = `src/pages/blog/${postSlug}.md`;

const posts = Object.values(import.meta.glob("../pages/blog/*.md", { eager: true }));
const myFeaturedPost = posts.find(post => post.file.includes(pathToMyFeaturedPost));
---

<p>
  Take a look at my favorite post, <a href={myFeaturedPost.url}>{myFeaturedPost.frontmatter.title}</a>!
</p>
```

### 타입 유틸리티 가져오기

#### Markdown 파일

`import.meta.glob()`로 로드된 Markdown 파일은 다음과 같은 `MarkdownInstance` 인터페이스를 반환합니다:

```ts
export interface MarkdownInstance<T extends Record<string, any>> {
  /* 이 파일의 YAML/TOML 프런트매터에 지정된 모든 데이터 */
	frontmatter: T;
  /* 이 파일의 절대 경로 */
	file: string;
  /* 이 파일의 렌더링된 경로 */
	url: string | undefined;
  /* 이 파일의 내용을 렌더링하는 Astro 컴포넌트 */
	Content: AstroComponentFactory;
  /** (Markdown만 해당) 레이아웃 HTML과 YAML/TOML 프런트매터를 제외한 원시 Markdown 파일 내용 */
	rawContent(): string;
  /** (Markdown만 해당) HTML로 컴파일된 Markdown 파일, 레이아웃 HTML 제외 */
	compiledContent(): string;
  /* 이 파일의 h1부터 h6까지의 요소들의 배열을 반환하는 함수 */
	getHeadings(): Promise<{ depth: number; slug: string; text: string }[]>;
	default: AstroComponentFactory;
}
```

TypeScript 제네릭을 사용하여 `frontmatter` 변수의 타입을 선택적으로 제공할 수 있습니다.

```astro
---
import type { MarkdownInstance } from 'astro';
interface Frontmatter {
    title: string;
    description?: string;
}

const posts = Object.values(import.meta.glob<MarkdownInstance<Frontmatter>>('./posts/**/*.md', { eager: true }));
---

<ul>
  {posts.map(post => <li>{post.frontmatter.title}</li>)}
</ul>
```

#### Astro 파일

Astro 파일은 다음과 같은 인터페이스를 가집니다:

```ts
export interface AstroInstance {
  /* 이 파일의 경로 */
  file: string;
  /* 이 파일의 URL (pages 디렉터리에 있는 경우) */
	url: string | undefined;
	default: AstroComponentFactory;
}
```

#### 기타 파일

다른 파일들은 다양한 인터페이스를 가질 수 있지만, 알 수 없는 파일 타입이 무엇을 포함하는지 정확히 알고 있다면 `import.meta.glob()`은 TypeScript 제네릭을 받습니다.

```ts
---
interface CustomDataFile {
  default: Record<string, any>;
}
const data = import.meta.glob<CustomDataFile>('../data/**/*.js');
---
```

### Glob 패턴

glob 패턴은 특수 와일드카드 문자를 지원하는 파일 경로입니다. 이는 프로젝트의 여러 파일을 한 번에 참조하는 데 사용됩니다.

예를 들어 glob 패턴 `./pages/**/*.{md,mdx}`는 페이지 하위 디렉터리에서 시작하여 모든 하위 디렉터리 (`/**`)를 검색하고 `.md` 또는 `.mdx` (`.{md,mdx}`)로 끝나는 모든 파일 이름 (`/*`)을 찾습니다.

#### Astro의 Glob 패턴

`import.meta.glob()`과 함께 사용하려면 glob 패턴이 문자열 리터럴이어야 하며 어떤 변수도 포함할 수 없습니다.

또한 glob 패턴은 다음 중 하나로 시작해야 합니다.

- `./` (현재 디렉터리에서 시작)
- `../` (상위 디렉터리에서 시작)
- `/` (프로젝트 루트에서 시작)

[glob 패턴 구문에 대해 자세히 알아보세요](https://github.com/micromatch/picomatch#globbing-features).

### `import.meta.glob()` vs `getCollection()`

[콘텐츠 컬렉션](/ko/guides/content-collections/)은 `import.meta.glob()` 대신 여러 파일을 가져오기 위한 [`getCollection()` API](/ko/reference/modules/astro-content/#getcollection)를 제공합니다. 콘텐츠 파일 (예: Markdown, MDX, Markdoc)이 `src/content/` 디렉터리의 컬렉션에 있는 경우 `getCollection()`을 사용하여 [컬렉션을 쿼리](/ko/guides/content-collections/#컬렉션-쿼리)하고 콘텐츠 항목을 반환합니다.

## WASM

```js
// 요청된 WASM 파일을 가져와 초기화합니다.
const wasm = await WebAssembly.instantiateStreaming(fetch('/example.wasm'));
```

Astro는 브라우저의 [`WebAssembly`](https://developer.mozilla.org/ko/docs/WebAssembly/JavaScript_interface) API를 사용하여 WASM 파일을 애플리케이션에 직접 로드하는 것을 지원합니다.

## Node 내장 기능

Astro는 몇 가지 제한 사항과 함께 Node의 최신 `node:` 접두사를 사용하여 Node.js 내장 기능을 지원합니다. 개발 환경과 프로덕션 환경 간에 차이가 있을 수 있으며, 일부 기능은 요청 시 렌더링과 호환되지 않을 수 있습니다. 일부 [어댑터](/ko/guides/on-demand-rendering/)는 이러한 내장 모듈과 호환되지 않거나, 일부 하위 집합을 지원하기 위해 구성이 필요할 수 있습니다. (예: [Cloudflare Workers](/ko/guides/integrations-guide/cloudflare/) 또는 [Deno](https://github.com/denoland/deno-astro-adapter))

다음 예시는 미디어 유형 (MIME)을 파싱하기 위해 Node의 `util` 모듈을 가져오는 방법을 보여줍니다.

```astro title="src/components/MyComponent.astro"
---
// 예: Node.js에 내장된 "util"을 가져옵니다.
import util from 'node:util';

export interface Props {
  mimeType: string,
}

const mime = new util.MIMEType(Astro.props.mimeType)
---

<span>타입: {mime.type}</span>
<span>하위 타입: {mime.subtype}</span>
```

## 파일 형식 지원 확장

**Vite** 및 호환되는 **Rollup** 플러그인을 사용하면 Astro에서 기본적으로 지원하지 않는 파일 형식을 가져올 수 있습니다. Vite 문서의 [플러그인 찾기](https://ko.vite.dev/guide/using-plugins.html#finding-plugins) 섹션에서 필요한 플러그인을 찾아보세요.

:::note[플러그인 구성]
구성 옵션과 올바르게 설치하는 방법은 플러그인 설명서를 참조하세요.
:::

<RecipeLinks slugs={['ko/recipes/add-yaml-support']} />
